home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / mcomm557.zip / SUPLMNT.DOC < prev    next >
Text File  |  1993-09-11  |  39KB  |  888 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.          ===============================================================
  7.  
  8.                           MCOMM SUPPLEMENTAL FUNCTIONS
  9.                   Mike Dumdei, 6 Holly Lane, Texarkana TX 75503
  10.  
  11.          ===============================================================
  12.  
  13.          The functions described in this document are non-async related
  14.          functions provided as part of the MCOMM library.  MCOMM is
  15.          first and foremost a serial I/O library, therefore, much more
  16.          effort went into describing the use of the async functions than
  17.          you will find here.  Also, because MCOMM is a serial library,
  18.          most of the supplemental functions are targeted towards commun-
  19.          ications programs.  The video functions correctly handle all
  20.          ANSI sequences commonly used by BBS systems.  They also support
  21.          windowed output, allowing you to limit the area of the screen
  22.          that will be written to.  For example, you can reserve the
  23.          bottom line of the screen for a status line and no writes, ANSI
  24.          clear screen commands, etc., will be allowed to overwrite or
  25.          erase it.
  26.  
  27.             ANSI sequences supported are:
  28.                CUP - cursor position
  29.                HVP - horizontal, vertical position
  30.                CUU - cursor up
  31.                CUD - cursor down
  32.                CUF - cursor forward
  33.                CUB - cursor backward
  34.                SCP - save cursor position
  35.                RCP - restore cursor position
  36.                ED  - erase display
  37.                EL  - erase line
  38.                SGR - set graphics rendition (colors)
  39.                FF  - form feed, not really ANSI, clears the screen
  40.  
  41.          Tabs, newlines, carriage returns, line feeds, backspace, the
  42.          bell character, etc. are supported also.  See the 'Global Video
  43.          Variables' section for information on options available for
  44.          handling control characters, scrolling, etc.
  45.  
  46.          In addition to the video routines, there are also timeout
  47.          functions, crc functions, string functions, a carrier watchdog
  48.          function, and several others.  On the following pages, the
  49.          video functions are listed first followed by the non-video type
  50.          functions.
  51.  
  52.          Distribution policy:
  53.             These functions are part of the MCOMM async library and may
  54.          not be distributed without the remaining MCOMM files.  No part
  55.          of the registered version may be distributed or used except as
  56.          stated in the license agreement.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.          GLOBAL VIDEO VARIABLES:
  64.  
  65.          v_seg - segment  address of video RAM, set by initvid()
  66.          v_mode - current video mode, set by initvid()
  67.          v_page - current video page, set by initvid()
  68.          v_color - attribute to use when displaying chars, this variable
  69.             is set directly by ANSI sequences that change the displayed
  70.             attribute and can be set from your C program to change the
  71.             current attribute (def = 7)
  72.          v_snow - snow flag, if 1 chars are written to screen during
  73.             vertical retrace, if 0 chars are written without waiting for
  74.             retrace
  75.          v_cga - a CGA video system was detected
  76.          v_bios - BIOS video flag, if 1 screen writes are performed
  77.             using BIOS INT 10, if 0 screen writes are done directly to
  78.             video RAM
  79.          v_wndsz - current window borders, set by SETWND macro
  80.             (def = 0,0,24,79)
  81.          v_btmrgt, v_rgt, v_btm, v_toplft, v_lft, v_top -
  82.             v_wndsz individual components
  83.          vs_wndsz - limits for d_msgat(), d_nchat(), & d_atrbat()
  84.          vs_btmrgt, vs_toplft  - vs_wndsz individual components
  85.          v_scrlm - scroll mode, if 1 then the window is scrolled when
  86.             the cursor would move off the bottom, if 0 the cursor wraps
  87.             back to the top  (def = 1)
  88.          v_cntrlm - control char handling, if 1 then control chars per-
  89.             form control functions, if 0 control chars are displayed as
  90.             graphic characters (def = 1)
  91.          v_textm - text mode, if 1 newlines are translated to CR/LF
  92.             pairs, if 0 newlines are displayed as LFs (def=1)
  93.          v_ansi - ansi mode, if 1 ANSI sequences are recognized, if 0
  94.             ANSI sequences are not recognized (def = 1)
  95.          v_wrel - if 1 cursor location arguments for functions that are
  96.             limited to the current window are relative to the top left
  97.             of the current window, if 0 cursor locations are absolute
  98.             (def = 0)
  99.          vs_wrel - if 1 cursor location arguments for functions that are
  100.             NOT limited to the current window are relative to the top
  101.             left of the current window, if 0 cursor locations are
  102.             absolute (def = 0)
  103.          v_ansiseq - shows that an ANSI sequence is currently in process
  104.             -- an ESC has been received by the display functions but the
  105.             terminating alpha character has not yet been received. (EX:
  106.             \33[0;36m is an ANSI sequence.  'v_ansiseq' is set to some
  107.             positive value when the ESC character is received and stay
  108.             positive until the sequence terminator is received.  When
  109.             the terminator is received, 'v_ansiseq' is set to a negative
  110.             value.  If the next character displayed after the terminator
  111.             is not the start of another ANSI sequence, 'v_ansiseq' is
  112.             reset to 0 after displaying that character.  This variable
  113.             is useful when stripping ANSI sequences from an incoming
  114.             stream of characters or when it is necessary to interrupt an
  115.             inprocess ANSI sequence.
  116.          v_bksp - if 1, backspace is destructive, if 0 backspace is not
  117.             destructive (def = 1)
  118.  
  119.  
  120.  
  121.  
  122.  
  123.          HANDLING OF UNSUPPORTED ANSI SEQUENCES:  (vers 5.52 change)
  124.  
  125.          When an unsupported ANSI sequence is displayed, the function
  126.          "x_ansi" is called. A default version of "x_ansi" that displays
  127.          the unrecognized sequence is included in the libraries.  To
  128.          override the default handler with one of your own, simply
  129.          put an "x_ansi" function in your code.  Your function will be
  130.          passed a pointer to any unrecognized ANSI sequences.   The
  131.          function prototype has the following form:
  132.  
  133.              void x_ansi(char *ansi_str);
  134.  
  135.          See TXZM.C for an example of function that overrides the
  136.          default "x_ansi" handler.
  137.  
  138.  
  139.          INTERRUPTING INPROCESS ANSI SEQUENCES:
  140.  
  141.          This section suggests some possible methods for handling the
  142.          situation where an ANSI sequence is in progress and it is nec-
  143.          essary to display characters that are not part of the sequence
  144.          and then resume the sequence.  An example of where this situa-
  145.          tion is a terminal program that is displaying incoming data
  146.          containing ANSI codes and the user of the program presses a key
  147.          that requires screen output in the middle of one of those
  148.          codes:
  149.                 Incoming data:    ESC[0;  (beginning of ANSI code)
  150.                 User keypress:     F1     (user wants a help screen)
  151.                 More incoming:    36m     (completion of ANSI code)
  152.  
  153.          The ANSI handler in the video library sees this:
  154.                   ESC[0;+----------------+
  155.                         |  Help Screen   |
  156.                         +----------------+36m
  157.          and since it doesn't know what to to with an ANSI code that
  158.          looks like that you see a small back arrow (for unrecognized
  159.          ANSI code), the help screen, and a 36m.
  160.  
  161.          To avoid this problem, you can do one of three things.  The
  162.          first is you can ignore the local user input until the
  163.          inprocess ANSI sequence is completed.  The v_ansiseq variable
  164.          described previously can be used to test whether or not an ANSI
  165.          sequence is currently in process.  Example:
  166.             if (KBHIT()) {
  167.                while (